﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>ASP.NET Boilerplate - Module Zero</title>
<link type="text/css" rel="stylesheet" href="../bootstrap.min.css" />
</head>

<body>

<div class="bs-callout bs-callout-warning">
	<h4>About Authorization</h4>
	<p>It's strongly suggested to read <a href="/Pages/Documents/Authorization">
	authorization documentation</a> before this document.</p>
</div>

<div class="document-contents">

<h3>Introduction</h3>
<p>Module-zero implements <strong>IPermissionChecker</strong> interface of 
ASP.NET Boilerplate's authorization system. To define and check permissions, you can see
<a href="/Pages/Documents/Authorization">authorization document</a>. In this 
document, we will see how to grant permissions for roles and users.</p>
	<h3>Role Permissions</h3>
	<p>If we <strong>grant</strong> a role for a permission, all users have this 
	role are authorized for the permission (unless explicitly prohibited for a 
	specific user). </p>
	<p>We use <strong>RoleManager</strong> to change permissions of a Role. For example,
	<strong>SetGrantedPermissionsAsync</strong> can be used to change all permissions of a role 
	in one method call:</p>
	<pre lang="cs">public class RoleAppService : IRoleAppService
{
    private readonly RoleManager _roleManager;
    private readonly IPermissionManager _permissionManager;

    public RoleAppService(RoleManager roleManager, IPermissionManager permissionManager)
    {
        _roleManager = roleManager;
        _permissionManager = permissionManager;
    }

    public async Task UpdateRolePermissions(UpdateRolePermissionsInput input)
    {
        var role = await _roleManager.GetRoleByIdAsync(input.RoleId);
        var grantedPermissions = _permissionManager
            .GetAllPermissions()
            .Where(p =&gt; input.GrantedPermissionNames.Contains(p.Name))
            .ToList();

        await _roleManager.SetGrantedPermissionsAsync(role, grantedPermissions);
    }
}</pre>
	<p>In this example, we get a <b>RoleId</b>
	and list of granted permission names (input.GrantedPermissionNames is a 
	List&lt;string&gt;) as input. We use <strong>IPermissionManager</strong> to find 
	all <strong>Permission</strong> objects by name. Then we call <strong>
	SetGrantedPermissionsAsync</strong> method to update permissions of the 
	role.</p>
	<p>There are also other methods like GrantPermissionAsync and 
	ProhibitPermissionAsync to control permissions one by one.</p>
	<h3>User Permissions</h3>
	<p>While role-based permission management can be enough for most 
	applications, we may need to control permissions per user. When we define a 
	permission setting for a user, it overrides permission setting comes from 
	roles of the user.</p>
	<p>As an example; Assume that we have an application service to prohibit a 
	permission for a user:</p>
	<pre lang="cs">public class UserAppService : IUserAppService
{
    private readonly UserManager _userManager;
    private readonly IPermissionManager _permissionManager;

    public UserAppService(UserManager userManager, IPermissionManager permissionManager)
    {
        _userManager = userManager;
        _permissionManager = permissionManager;
    }

    public async Task ProhibitPermission(ProhibitPermissionInput input)
    {
        var user = await _userManager.GetUserByIdAsync(input.UserId);
        var permission = _permissionManager.GetPermission(input.PermissionName);

        await _userManager.ProhibitPermissionAsync(user, permission);
    }
}</pre>
	<p>UserManager has many methods to control permissions for users. In this 
	example, we're getting a UserId and PermissionName and using UserManager's
	<strong>ProhibitPermissionAsync</strong> method to prohibit a permission for 
	a user. </p>
	<p>When we <strong>prohibit</strong> a permission for a user, he/she <strong>
	can not</strong> be authorized for this permission even his/her roles are
	<strong>granted</strong> for the permission. We can say same principle for 
	granting. When we <strong>grant</strong> a permission specifically for a 
	user, this user <strong>is granted</strong> for the permission even roles of 
	the user are not granted for the permission. We can use <strong>
	ResetAllPermissionsAsync</strong> for a user to delete all user-specific 
	permission settings for the user.</p>

</div>

</body>

</html>
